luci-base: jsdoc Slider -> RangeSlider and fixes for RangeSlider

The usecalc property suffers from recursive calculation; that is, its
output becomes its input at the next save. It is not known in advance
whether a stored value is one that was calculated or not. So this part
was removed. The getCalculatedValue() function is retained should it be
desirable to get this value.

The 'optional' property was removed since it didn't do anything.
The 'validate' property is now correctly bound.

Signed-off-by: Paul Donald <[email protected]>

diff --git a/modules/luci-base/htdocs/luci-static/resources/form.js b/modules/luci-base/htdocs/luci-static/resources/form.js
index 7d3d2acd74a3d59be99a05be27f197f03876fb1b..9a8523c62fe2ae1ed492dfb4d2cd459ee7edafc5 100644 (file)
--- a/modules/luci-base/htdocs/luci-static/resources/form.js
+++ b/modules/luci-base/htdocs/luci-static/resources/form.js
@@ -4209,38 +4209,19 @@ const CBIRangeSliderValue = CBIValue.extend(/** @lends LuCI.form.RangeSliderValu
         * @default null
         */
 
-       /**
-        * Whether to use the calculated result of the chosen value instead of the
-        * chosen value: the result of the calculation returned by the
-        * <code>calculate</code> function on the chosen value
-        * is written to the configuration instead of the chosen value. The
-        * <code>calcunits</code> displayed units are not included. 
-        * 
-        * Note: Implementers of the <code>calculate</code> function shall be
-        * mindful that it may be possible to return a NaN value which is seldom a
-        * sensible input for the underlying daemon or system. Verification of any
-        * calculated value is an exercise left to the implementer.
-        *
-        * @name LuCI.form.RangeSliderValue.prototype#usecalc
-        * @type boolean
-        * @default false
-        */
-
        /** @private */
        renderWidget(section_id, option_index, cfgvalue) {
                const slider = new ui.RangeSlider((cfgvalue != null) ? cfgvalue : this.default, {
                        id: this.cbid(section_id),
                        name: this.cbid(section_id),
-                       optional: this.optional,
                        min: this.min,
                        max: this.max,
                        step: this.step,
                        calculate: this.calculate,
                        calcunits: this.calcunits,
-                       usecalc: this.usecalc,
                        disabled: this.readonly || this.disabled,
                        datatype: this.datatype,
-                       validate: this.validate,
+                       validate: L.bind(this.validate, this, section_id),
                });
 
                this.widget = slider;
@@ -4255,15 +4236,13 @@ const CBIRangeSliderValue = CBIValue.extend(/** @lends LuCI.form.RangeSliderValu
         * The configuration section ID
         *
         * @returns {*}
-        * Returns the current input value.
+        * Returns the currently selected value if it does not match the default.
+        * If the currently selected value matches the default value, returns null.
         */
        formvalue(section_id) {
                const elem = this.getUIElement(section_id);
                if (!elem) return null;
-               let val = (this.usecalc && (typeof this.calculate === 'function'))
-                       ? elem.getCalculatedValue()
-                       : elem.getValue();
-               val = val?.toString();
+               const val = elem.getValue().toString();
                return (val === this.default?.toString()) ? null : val;
        }
 });

diff --git a/modules/luci-base/htdocs/luci-static/resources/ui.js b/modules/luci-base/htdocs/luci-static/resources/ui.js
index 1c287aeeb8cb7f05abe34837b7ebe554e96db7d4..b7eff98d703a859e9025bcc958b466fd39ac7046 100644 (file)
--- a/modules/luci-base/htdocs/luci-static/resources/ui.js
+++ b/modules/luci-base/htdocs/luci-static/resources/ui.js
@@ -2647,7 +2647,7 @@ const UIDynamicList = UIElement.extend(/** @lends LuCI.ui.DynamicList.prototype
 /**
  * Instantiate a range slider widget.
  *
- * @constructor Slider
+ * @constructor RangeSlider
  * @memberof LuCI.ui
  * @augments LuCI.ui.AbstractElement
  *
@@ -2661,25 +2661,53 @@ const UIDynamicList = UIElement.extend(/** @lends LuCI.ui.DynamicList.prototype
  * instantiating CBI forms.
  *
  * This class is automatically instantiated as part of `LuCI.ui`. To use it
- * in views, use `'require ui'` and refer to `ui.Slider`. To import it in
+ * in views, use `'require ui'` and refer to `ui.RangeSlider`. To import it in
  * external JavaScript, use `L.require("ui").then(...)` and access the
- * `Slider` property of the class instance value.
+ * `RangeSlider` property of the class instance value.
  *
  * @param {string|string[]} [value=null]
- * ...
+ * The initial value to set the slider handle position.
  *
+ * @param {LuCI.ui.RangeSlider.InitOptions} [options]
+ * Object describing the widget specific options to initialize the range slider.
  */
 const UIRangeSlider = UIElement.extend({
+       /**
+        * In addition to the [AbstractElement.InitOptions]{@link LuCI.ui.AbstractElement.InitOptions}
+        * the following properties are recognized:
+        *
+        * @typedef {LuCI.ui.AbstractElement.InitOptions} InitOptions
+        * @memberof LuCI.ui.RangeSlider
+        *
+        * @property {int} [min=1]
+        * Specifies the minimum value of the range.
+        *
+        * @property {int} [max=100]
+        * Specifies the maximum value of the range.
+        *
+        * @property {int} [step=1]
+        * Specifies the step value of the range slider handle.
+        *
+        * @param {function} [calculate=null]
+        * A function to invoke when the slider is adjusted by the user. The function
+        * performs a calculation on the selected value to produce a new value.
+        *
+        * @property {string} [calcunits=null]
+        * Specifies a suffix string to append to the calculated value output.
+        *
+        * @property {boolean} [disabled=false]
+        * Specifies whether the the widget is disabled.
+        *
+        */
+
        __init__(value, options) {
                this.value = value;
                this.options = Object.assign({
-                       optional: true,
                        min: 0,
                        max: 100,
                        step: 1,
                        calculate: null,
                        calcunits: null,
-                       usecalc: false,
                        disabled: false,
                }, options);
        },
@@ -2744,7 +2772,12 @@ const UIRangeSlider = UIElement.extend({
                return this.sliderEl.value;
        },
 
-       /** @private */
+       /**
+        * Return the value calculated by the `calculate` function.
+        *
+        * @instance
+        * @memberof LuCI.ui.RangeSlider
+        */
        getCalculatedValue() {
                return this.calculatedvalue;
        },